ShieldRect.lib is a Mac OS PPC only library that provides a mechanism that allows you to register a rectangular region of the screen and be notified BEFORE it is overwritten or changed in any way.
Who needs it?
Anyone who is drawing to the screen asynchronously. This includes hardware drawing systems (such as a hardware 3D card) and software drawing systems such as a multi-processor (multi-threaded) drawing engine. This document focuses on RAVE engines capable of asynchronous drawing.
Who is it NOT for?
This system will probably not be used in Rhapsody. Rhapsody will most likely have a different scheme for locking screen real estate. It might be used in the Rhapsody blue box.
Why is it needed?
Historically, in the Mac OS drawing to the screen is only allowed during “Event Time”. That is, when an application returns from a call to WaitNextEvent. Asynchronous drawing was not allowed. If you attempted it you would run the risk of overwriting menus and windows and such things. And if the user changed the screen depth or resolution, you run the risk of drawing into a portion of memory that may be in use by another process.
To illustrate the problem lets look at a typical RAVE drawing loop.
1. App calls QARenderStart()
2. App starts submitting triangles to render.
At this point the hardware might start rendering to the screen or to a back buffer.
3. App calls QARenderEnd()
4. App continues on, and possibly handles user events.
At this point the hardware might still be rendering to the screen.
If the hardware is double buffering, at some point it will have to blit to the screen.
The problem arises in step 4. The user might pull down a menu that covers the portion of the screen that the hardware is rendering to. The menu will pop down and then promptly be overwritten by the 3D hardware. The user gets mad and blames the 3D hardware. This problem is not restricted to the user pulling down a menu. Here are some more possible problems...
user pulls down a menu
user moves another window over the window being rendered to
user switches to another app
user hides the 3D app
balloon help pops up
dialog or alert box pops up
user changes screen resolution, depth, or position
screen saver starts
screen goes to sleep
user drags something (an icon) across the window being rendered to
etc...
How do I use it?
There are two calls, RegisterShieldRect and UnregisterShieldRect.
When you call RegisterShieldRect you pass a Rect in global coords, a function pointer (to a notify function that you provide), and a refCon.
When that rectangle is about to be overwriten your notify function will be called.
(Your notify function is also called before the screen depth, resolution or position changes.)
When your notify function is called it gets passed a rectangle indicating the portion of the screen about to be overwriten and the refCon that you passed to RegisterShieldRect.
Here is how I see this being used inside a RAVE engine...
When the RAVE engine creates a draw context register the rectangle and your notify function with RegisterShieldRect.
When your notify function gets called, check if your hardware has any drawing pending for the given draw context. If so, wait until your hardware is finished drawing, then return.
When you delete your draw context, unregister your notify function by calling UnregisterShieldRect.
